home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu374.dms / pu374.adf / Animan / VoiceLib.doc / VoiceLib.doc
Text File  |  1992-11-17  |  14KB  |  394 lines
  1. *****************************************************************
  2.  
  3.    Voice Recognition for the Amiga using an audio digitizer.
  4.  
  5.    Voice.library (Ver 6.6) by Richard Horne - February 1993
  6.  
  7. *****************************************************************
  8.  
  9. FUNCTION OFFSET DEFINITIONS
  10.  
  11.    _LVOLearn           EQU   -30
  12.    _LVORecognize       EQU   -36
  13.    _LVOAddVoiceTask    EQU   -42
  14.    _LVORemVoiceTask    EQU   -48
  15.    _LVOGainUp          EQU   -54
  16.    _LVOGainDown        EQU   -60
  17.    _LVORecDataAddress  EQU   -66
  18.    _LVORecMapAddress   EQU   -72
  19.    _LVOWordScore       EQU   -78
  20.    _LVOPickSampler     EQU   -84
  21.    _LVOSetVoicePri     EQU   -90
  22.    _LVOPickTimer       EQU   -96
  23.  
  24. ************************* FUNCTION DEFINITIONS ******************
  25.  
  26. >>>>> All variables are long words unless otherwise noted. <<<<<<
  27.  
  28. NOTE:  Voice.library is opened with a call to the exec OpenLibrary
  29. function.  OpenLibrary can fail for one of three reasons:
  30.  
  31. 1.  The voice.library file is not available in the libs: directory or
  32.     cannot be found.
  33.  
  34. 2.  The parallel port is busy.
  35.  
  36. 3.  Voice.library is currently opened and being used by another
  37.     application program.
  38.  
  39. *****************************************************************
  40.  
  41. NAME:      
  42. Learn -- Learn a spoken phrase.
  43.  
  44. OFFSET:      
  45. -30
  46.  
  47. SYNOPSIS:
  48. MapAddress = Learn (MapBuffer, Text, Screen, SequenceNum, X, Y)
  49. d0                  a0         a1    a2      d0           d1 d2
  50.  
  51. FUNCTION:
  52. The "Learn" function stores a frequency map of a spoken word or
  53. phrase.  Each frequency map is made up of 72 long words of data
  54. plus a 16 byte header for the associated ASCII text (304 bytes
  55. total).  "Learn" requires the user to reserve a MapBuffer in
  56. memory equal to the size of vocabulary desired (number of words)
  57. times 304 bytes.  MapBuffer address is passed to "Learn" in a0. 
  58. Address of a null terminated text string representing the word or
  59. phrase to be learned is passed to "Learn" in a1.
  60.  
  61. The "Learn" function will open it's own window on the screen
  62. specified in a2 (use NULL for WBENCHSCREEN), at a position X, Y
  63. specified in d1 and d2.  The user will then be prompted to speak
  64. the specified word or phrase to obtain three good digital
  65. samples.  Internally, these three samples are analyzed for
  66. frequency content and transformed into a frequency map (304
  67. bytes) which is stored in the MapBuffer according to the Sequence
  68. Number specified in d0.  "Learn" returns the memory address
  69. within MapBuffer at which this particular frequency map is
  70. stored.  If "Learn" is intentionally cancelled using the close
  71. gadget of the Learn Window, then a zero will be returned.
  72.  
  73. "Learn" is called separately for each word or phrase in the
  74. vocabulary.  After every word has been learned, MapBuffer will be
  75. filled with a sequence of frequency maps (each 304 bytes).  Then
  76. the "Recognize" or "AddVoiceTask" functions can be called which
  77. will listen to the audio digitizer, compute a frequency map
  78. of incoming words compare them to the words in MapBuffer, and
  79. indicate by Sequence Number which word or phrase is the best
  80. match.  The maximum number of words or phrases in the vocabulary
  81. is 64.
  82.  
  83. Note that you must select an audio sampler (PerfectSound3,
  84. SoundMaster, or Generic) using the "PickSampler" function before
  85. using the "Learn" function.
  86.  
  87. *****************************************************************
  88.  
  89. NAME:
  90. Recognize -- Recognize a spoken word or phrase.
  91.  
  92. OFFSET:
  93. -36
  94.  
  95. SYNOPSIS:
  96. SequenceNum = Recognize (MapBuffer, SizeVocabulary, Resolution)
  97. d0                       a0         d0              d1 
  98.  
  99. FUNCTION:
  100. "Recognize" assumes that the user has learned a sequence of words
  101. or phrases using the "Learn" function.  MapBuffer contains a
  102. sequence of frequency maps produced by "Learn" corresponding to
  103. each word or phrase in the vocabulary.  Mapbuffer address is
  104. passed to "Recognize" in a0.  Number of words or phrases in the
  105. vocabulary are passed to "Recognize" in d0.
  106.  
  107. "Recognize" listens for an incoming word, computes it's frequency
  108. map, and compares this map to the sequence of maps contained in
  109. MapBuffer.  The Sequence Number of the word or phrase in
  110. MapBuffer which is most similar to that of the incoming word is
  111. returned in d0.  Note that the number "0" represents the first
  112. word, "1" the second, and so on.
  113.  
  114. "Recognize" will operate at either high resolution (d1 = 0) or
  115. low resolution (d1 = 1).  High resolution computes a frequency
  116. analysis of the incoming word or phrase at twice the number of
  117. points in time as low resolution.  High resolution is somewhat
  118. better at word recognition, but takes almost twice the processing
  119. time.
  120.  
  121. "Recognize" will return the following error codes if it cannot
  122. find a match.
  123.  
  124. d0 = -1 if there is no match between the incoming frequency map  
  125.    and any of the maps in MapBuffer.
  126.  
  127. d0 = -2 if the incoming word causes unacceptable digital
  128.    clipping.  Volume should be reduced by moving your
  129.    microphone or by using the "GainDown" function.
  130.     
  131. d0 = -3 if incoming word is too low in volume.  Volume should be
  132.    increased by moving your microphone or by using the "GainUp"
  133.    function.
  134.  
  135. d0 = -4 if the incoming sample is confused by extraneous noise.
  136.  
  137. *****************************************************************
  138.  
  139. NAME:      
  140. AddVoiceTask -- Initiate a separate task to recognize a spoken 
  141.                 word or phrase.
  142.  
  143. OFFSET:      
  144. -42
  145.  
  146. SYNOPSIS:
  147. AddVoiceTask (MapBuffer, MsgPort, SizeVocabulary, Resolution)
  148.               a0         a1       d0              d1
  149.  
  150. FUNCTION:
  151. "AddVoiceTask" is similar in function to "Recognize" except that
  152. here, a separate task is started under the Amiga multitasking
  153. operating system which listens for incoming words or phrases and
  154. returns messages to the user's Message Port indicating the
  155. Sequence Number of the frequency map in Mapbuffer which best
  156. matches the frequency map of the incoming word.  MapBuffer
  157. address and Message Port address are passed to "AddVoiceTask"
  158. in a0 and a1.  Number of words or phrases in the vocabulary are
  159. passed to "AddVoiceTask" in d0.
  160.  
  161. "AddVoiceTask" will operate at either high resolution (d1 = 0) or
  162. low resolution (d1 = 1).  High resolution computes a frequency
  163. analysis of the incoming word or phrase at twice the number of
  164. points in time as low resolution.  High resolution is somewhat
  165. better at word recognition, but takes almost twice the processing
  166. time.
  167.  
  168. The messages sent to MessagePort are designed to mimic shortened
  169. IDCMP messages with a im_Class = $0.  Thus you can receive and
  170. process these messages at either an Intuition window IDCMP
  171. message port or at a custom message port of your own.
  172. Messages sent by this task are as follows.
  173.  
  174. im_Code = Sequence number of frequency map in MapBuffer that
  175.           best matches the frequency map of the incoming
  176.           word or phrase.
  177.  
  178. im_Code = -1 if there is no match between the incoming
  179.           frequency map and any of the maps in MapBuffer.
  180.  
  181. im_Code = -2 if the incoming word causes unacceptable
  182.           digital clipping.  Volume should be reduced by
  183.           moving your microphone or by using the "GainDown"
  184.           function.
  185.  
  186. im_Code = -3 if incoming word is too low in volume.  Volume
  187.           should be increased by moving your microphone or
  188.           by using the "GainUp" function.
  189.  
  190. im_Code = -4 if the incoming sample is confused by
  191.           extraneous noise.
  192.  
  193. Upon calling "AddVoiceTask", the PerfectSound digitizer becomes
  194. immediately active, listening for an incoming word.  After
  195. receipt of a word or phrase, a message as described above is sent
  196. to Message Port.  The VoiceTask then goes into a WAIT mode and
  197. remains inactive until it receives a reply to the message it has
  198. sent to Message Port.  Upon receipt of a reply, VoiceTask again
  199. becomes goes active and listens for an incoming word.  The priority
  200. of this task will be 127 for fastest possible voice recognition.
  201. You may change this priority to a lower value with the "SetVoicePri"
  202. task.
  203.  
  204. *****************************************************************
  205.  
  206. NAME:      
  207. RemVoiceTask -- Remove task initiated by AddVoiceTask
  208.  
  209. OFFSET:      
  210. -48
  211.  
  212. SYNOPSIS:
  213. RemVoiceTask ()
  214.    
  215. FUNCTION:
  216. Deallocates memory and removes VoiceTask from the Amiga system.
  217. Note that the Message Port specified for the "AddVoiceTask" function
  218. must still exist at the time you call "RemVoiceTask".  Also you
  219. must reply to all outstanding messages from VoiceTask BEFORE calling
  220. this function.
  221.  
  222. *****************************************************************
  223.  
  224. NAME:
  225. GainUp -- Increase gain of PerfectSound 3 audio digitizer.
  226.  
  227. OFFSET:
  228. -54
  229.  
  230. SYNOPSIS:
  231. GainUp()
  232.  
  233. FUNCTION:
  234. Increases gain of the PerfectSound audio digitizer by one step. 
  235. Note that when gain reaches maximum, "GainUp" will wrap around
  236. and return gain to it's lowest value.  Do not call this function
  237. if you are using the SoundMaster audio digitizer.
  238.  
  239. *****************************************************************
  240.  
  241. NAME:
  242. GainDown -- Decease gain of PerfectSound 3 audio digitizer.
  243.  
  244. OFFSET:
  245. -60
  246.  
  247. SYNOPSIS:
  248. GainDown()
  249.  
  250. FUNCTION:
  251. Decreases gain of the PerfectSound audio digitizer by one step. 
  252. Note that when gain reaches minimum, "GainDown" will wrap around
  253. and return gain to it's highest value.  Do not call this function
  254. if you are using the SoundMaster audio digitizer
  255.  
  256. *****************************************************************
  257.  
  258. NAME:
  259. RecDataAddress -- Return memory address of digital sample of
  260.                   incoming word or phrase.
  261.  
  262. OFFSET:
  263. -66
  264.  
  265. SYNOPSIS:
  266. Address = RecDataAddress()
  267. d0
  268.  
  269.  
  270. FUNCTION:
  271. When an incoming word or phrase is digitized, 3/4 second of
  272. digital data is stored in an internal buffer.  This is 8 bit
  273. digitized data is sampled at a rate of 6400 Hz.  Thus the buffer
  274. for storing this data is 4800 bytes in size.  This function
  275. returns the address of this buffer for possible additional
  276. experimental uses.
  277.  
  278. *****************************************************************
  279.  
  280. NAME:
  281. RecMapAddress -- Return memory address of frequency map of
  282.                  incoming word or phrase.
  283.  
  284. OFFSET:
  285. -72
  286.  
  287. SYNOPSIS:
  288. Address = RecMapAddress()
  289. d0
  290.  
  291. FUNCTION:
  292. A frequency map of each incoming word or phrase is computed for
  293. comparison with maps learned and stored in MapBuffer.  Each map
  294. consists of a frequency analysis of 3/4 second of audio data at
  295. 72 points in time.  For each of these 72 time points, the data is
  296. examined for frequency content at 32 points between 0 Hz and 3200
  297. Hz.  A frequency map is made up of 72, 32 bit words corresponding
  298. to the 72 time points analyzed.  For each of these 32 bit words,
  299. bit 0 is set if the signal contains frequency components from 
  300. 0-100 Hz.  Bit 1 is set if the signal contains frequency
  301. components from 100-200 Hz.  Bit 2 is set if the signal contains
  302. frequency components from 200-300 Hz etc.  This function returns
  303. the address of this frequency map for possible additional
  304. experimental uses.  Note that this internal frequency map does
  305. not have the 16 byte ASCII header as do the frequency maps
  306. stored in MapBuffer.
  307.  
  308. *****************************************************************
  309.  
  310. NAME:
  311. WordScore -- Return recognition score of a recognized word.
  312.  
  313. OFFSET:
  314. -78
  315.  
  316. SYNOPSIS:
  317. Value = WordScore()
  318. d0
  319.  
  320. FUNCTION:
  321. The "Recognize" function computes a numerical score representing the
  322. "goodness" of a match between the frequency map of an incoming word
  323. and each frequency map stored in MapBuffer.  The recognized word
  324. is determined by highest score.  This function returns the score value
  325. for the recognized word.  Internally, a score of #2000 must be achieved
  326. in order for a match to be declared.  If you wish to have a higher match
  327. score threshold to reduce false matches, you may call "WordScore" after
  328. each word is recognized and set your own higher score threshold before
  329. accepting a match.  Increasing the match score threshold will reduce
  330. false matches, but will also decrease recognition performance.
  331.  
  332.  
  333. *****************************************************************
  334.  
  335. NAME:      
  336. PickSampler -- Specify which model audio sampler to use (either
  337.                PerfectSound3, SoundMaster, or Generic).
  338.  
  339. OFFSET:      
  340. -84
  341.  
  342. SYNOPSIS:
  343. PickSampler (SamplerID)
  344.                 d0
  345.  
  346. FUNCTION:
  347. Select the audio sampler to be used with this function.  SamplerID = 0
  348. for PerfectSound3.  SamplerID = 1 for SoundMaster.  SamplerID = 2 for
  349. Generic Sampler.
  350.  
  351. *****************************************************************
  352.  
  353. NAME:
  354. SetVoicePri -- Set the multitasking priority of a voice recognition
  355.                task that has been started by the "AddVoiceTask"
  356.                function.
  357.  
  358. OFFSET:
  359. -90
  360.  
  361. SYNOPSIS:
  362. Old Priority = SetVoicePri (New Priority)
  363. d0                          d0
  364.  
  365. FUNCTION:
  366. When "AddVoiceTask" is called, a voice recgnition task of priority 127
  367. is started for the fastest possible voice recognition.  You may modify
  368. this priority by setting New Priority to any value between -128 and 127
  369. and calling "SetVoicePri" which changes task priority to the new value
  370. and returns the value of the old task priority.  "AddVoiceTask" must
  371. be called before "SetVoicePri."
  372.  
  373. *****************************************************************
  374.  
  375. NAME:
  376. PickTimer -- Select either Timer A or Timer B of the CIA B for use
  377.              in timing digital audio samples.
  378.  
  379. OFFSET:
  380. -96
  381.  
  382. SYNOPSIS:
  383. PickTimer(TimerID)
  384.             d0
  385.  
  386. FUNCTION:
  387. Voice.library uses CIA B Timer B by default for setting the time interval
  388. between digital audio samples.  You may find situations where other
  389. applications require Timer B, causing a conflict.  Use this function to
  390. choose either Timer B or Timer A as required.  TimerID = 0 for selection
  391. of Timer B.  TimerID = 1 for selection of Timer A.
  392.  
  393.  
  394.